#Curve25519 WebCrypto

Each example below is an independent full App script. Import webcrypto from the built-in node:crypto; no npm installation is needed. Lowercase global crypto is the same WebCrypto object and needs no import; do not import it from scripting. Uppercase global Crypto is the separate Data-based API. TextEncoder, TextDecoder and console are globals.

Ordinary scripts can use crypto.subtle directly or require('node:crypto').webcrypto.subtle. Both refer to the same existing WebCrypto implementation; no import from scripting is needed.

#Operations and key formats

generateKey returns {privateKey, publicKey}. A generated public key is extractable. A private key requires at least one valid usage. Use raw for 32-byte public keys, SPKI for public keys, PKCS8 for private keys, or OKP JWK for either. DER requires the correct RFC8410 curve identifier without algorithm parameters. JWK validates curve, key type, extraction and usages; public/private material must match. Ed25519 JWK export uses alg: 'Ed25519' and import also accepts the older EdDSA value.

#Complete signing example

Prints true after verifying the generated signature.

import { webcrypto } from "node:crypto"

// crypto.subtle is also global; TextEncoder and console need no import.
const signing = await webcrypto.subtle.generateKey("Ed25519", false, ["sign", "verify"])
const message = new TextEncoder().encode("hello")
const signature = await webcrypto.subtle.sign("Ed25519", signing.privateKey, message)
console.log(await webcrypto.subtle.verify("Ed25519", signing.publicKey, signature, message)) // true

#Complete two-party key-agreement example

Creates both peers locally, round-trips hello, and has no external remotePublicBytes prerequisite.

import { webcrypto } from "node:crypto"

const subtle = webcrypto.subtle
const alice = await subtle.generateKey("X25519", false, ["deriveKey"])
const bob = await subtle.generateKey("X25519", false, ["deriveKey"])
// Self-contained demo: Bob supplies the peer public bytes. Authenticate them in a real protocol.
const bobPublicBytes = await subtle.exportKey("raw", bob.publicKey)
const bobPublic = await subtle.importKey("raw", bobPublicBytes, "X25519", true, [])
const aliceKey = await subtle.deriveKey(
  { name: "X25519", public: bobPublic }, alice.privateKey,
  { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"],
)
const bobKey = await subtle.deriveKey(
  { name: "X25519", public: alice.publicKey }, bob.privateKey,
  { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"],
)
const iv = webcrypto.getRandomValues(new Uint8Array(12))
const ciphertext = await subtle.encrypt({ name: "AES-GCM", iv }, aliceKey, new TextEncoder().encode("hello"))
const plaintext = await subtle.decrypt({ name: "AES-GCM", iv }, bobKey, ciphertext)
console.log(new TextDecoder().decode(plaintext)) // hello

Obtain and authenticate the peer's public key through your protocol. X25519 alone does not authenticate the peer. For a complete protocol, use its specified key derivation and authentication steps. Ed25519 signatures may vary between calls on systems using randomized signing; verify signatures instead of comparing generated bytes.

deriveBits requires the private key's deriveBits usage. It accepts null for all 256 bits or an integer from 0 through 256, returning the requested prefix with unused final bits cleared. Invalid or all-zero shared secrets reject. deriveKey requires deriveKey usage and directly creates an opaque native secret key; it does not expose shared bytes. Targets are AES-GCM with 128/192/256 bits and encrypt/decrypt usages, or HMAC with SHA-1/256/384/512, an explicit positive byte-aligned length up to 256 bits, and sign/verify usages. Omitting HMAC length chooses the hash block size, which exceeds X25519's 256-bit result and therefore rejects.

Curve keys and newly derived secret keys expose immutable metadata and keep their material in native handles. Nonextractable keys cannot be exported by changing JavaScript properties. Derived AES-GCM supports a 12-byte IV, a 128-bit tag and optional additionalData. Use a fresh IV for every encryption with a key. Buffers retain typed-array offsets; each native message or additionalData input is limited to 16 MiB.

Invalid key formats, types, usages and operations reject with named WebCrypto errors. Unsupported curves, Ed25519ph, key wrapping, Apple pairing and service protocols are outside this API.

Node modules and import guide.

#Handling access errors

Extended cryptography operations check access in the native runtime, including operations on previously created keys. Catch rejected promises and inspect error.code; an access denial uses ERR_PRO_REQUIRED. Do not retry cryptographic work indefinitely after an access denial.